Update (2026-04-23): Enforcement reduced from 3 modes to 2 — permissive (new default) and enforcing. The disabled mode is gone; existing deployments passing --authorization-enforcement=disabled are auto-migrated to permissive with a one-time INFO log, so no operator action is required. New Prometheus signals (authorizer_authz_checks_total, authorizer_authz_unmatched_total, authorizer_authz_check_duration_seconds) plus a rate-limited authz.unmatched warn log give operators the visibility needed to flip from permissive → enforcing once permissions are seeded. Watch authorizer_authz_unmatched_total{mode="permissive"} trend to zero before flipping. See docs/superpowers/specs/2026-04-21-authz-two-mode-enforcement-design.md.

Summary

Implements RFC #508 — Fine-Grained Authorization with a Keycloak-inspired four-pillar model (Resources, Scopes, Policies, Permissions). This replaces the flat comma-separated role strings with a composable, principal-agnostic authorization engine.

Key features

• Resources — define what you're protecting (e.g., "document", "invoice")
• Scopes — define allowed actions (e.g., "read", "write", "delete")
• Policies — define who gets access via role-based or user-based conditions, with positive/negative logic
• Permissions — bind resources + scopes + policies with affirmative or unanimous decision strategies
• Policy Evaluation Engine — principal-agnostic (supports users, M2M clients, AI agents), with in-memory caching, negative caching, input validation, and 2 enforcement modes (permissive default / enforcing)
• REST endpoint — POST /api/v1/check-permission for downstream services
• Dashboard UI — 5 pages (Resources, Scopes, Policies, Permissions, Evaluate) with natural language permission summaries and a policy evaluation test tool

Observability

• Prometheus collectors: authorizer_authz_checks_total{mode,result}, authorizer_authz_unmatched_total{mode}, authorizer_authz_check_duration_seconds
• Rate-limited authz.unmatched=true warn log (1 per (resource, scope) per 60s) on permissive fallthroughs
• In-process per-(resource, scope) unmatched counter (foundation for future "Uncovered checks" dashboard view)
• Startup banner: mode-aware INFO plus a loud WARN when booting enforcing with 0 permissions configured

Backward compatibility

• Default is --authorization-enforcement=permissive — unmatched checks are ALLOWED and logged, so apps keep working while operators seed permissions
• Legacy --authorization-enforcement=disabled is silently normalized to permissive with a one-time INFO log — no operator action required during upgrade
• Existing User.Roles field, IsSuperAdmin() checks, and JWT format are unchanged
• Permissions are only added to JWT when --include-permissions-in-token=true

Future-proof for M2M and AI agents

• Principal abstraction accepts any identity type (user, client, agent)
• MaxScopes delegation ceiling for token-scoped restrictions
• Extensible policy types — adding "client" or "agent" is one switch case, no schema migration

Storage

• 7 new tables across all 13 database providers (SQL via GORM, MongoDB, ArangoDB, Cassandra, Couchbase, DynamoDB)
• 28 new storage interface methods per provider
• Optimized GetPermissionsForResourceScope JOIN query for the evaluation hot path

New CLI flags

• --authorization-enforcement (permissive default / enforcing; legacy disabled auto-migrated)
• --authorization-cache-ttl (default: 300s)
• --include-permissions-in-token (default: false)
• --authorization-log-all-checks (default: false)

Test plan

• 16 integration tests pass (SQLite): CRUD for all entities, permission evaluation with role-based policies, referential integrity on delete, cleanup
• 8 new integration tests pass (SQLite): permissive-allow-no-data, enforcing-deny-no-data, explicit-deny-in-permissive-still-denies, Prometheus counter increment, and 4 TestConfig_* migration tests
• go build ./... passes
• go vet ./... passes
• Dashboard npm run build passes
• Manual testing: start with make dev, navigate to Authorization in dashboard, create resource/scope/policy/permission, test evaluate page
• Test with --authorization-enforcement=enforcing to verify default-deny behavior
• Test REST endpoint with curl -X POST /api/v1/check-permission
• Smoke-boot with --authorization-enforcement=disabled to confirm the legacy-migration INFO log fires and the server boots in permissive mode

Design specs

• docs/superpowers/specs/2026-04-13-fine-grained-authorization-design.md — original FGA design
• docs/superpowers/specs/2026-04-21-authz-two-mode-enforcement-design.md — two-mode enforcement refactor